--- title: "Create payment" method: POST path: "/payments " --- # Create payment `POST /payments ` ## Headers - `Content-Type` string, required - `Host` string, required - `Date` string, required - `Digest` string, required - `Authorization` string, required - `Idempotency-Key` string - `x-satispay-deviceinfo` string - `x-satispay-devicetype` 'SMARTPHONE' | 'TABLET' | 'CASH REGISTER' | 'POS' | 'PC' | 'ECOMMERCE_PLUGIN' - `x-satispay-os` string - `x-satispay-osv` string - `x-satispay-apph` string - `x-satispay-appn` string - `x-satispay-appv` string - `x-satispay-tracking-code` string ## Request body - object - `flow` 'MATCH_CODE' | 'MATCH_USER' | 'FUND_LOCK' | 'REFUND', required — The payment flows that you can use with Fringe Benefits are:

`MATCH_CODE` [DOC](https://developers.satispay.com/docs/one-off)
This flow can be used generically for one-off payments.

`MATCH_USER` [DOC](https://developers.satispay.com/docs/payment-mobile-number)
This flow can be used for one-off payments on a specific user.
To use this flow you must also include the `consumer_uid` parameter.

`FUND_LOCK` [DOC](https://developers.satispay.com/docs/funds-lock-late-capture)
This flow can be used for funds lock payments.

`REFUND` [DOC](https://developers.satispay.com/reference/refund)
This flow can be used for refunds on a specific payment.
To use this flow you must also include the `parent_payment_uid` and the `amount_unit`. - `amount_unit` integer, required — The payment amount in cents.

For example, to represent the amount `€12.40`, you should multiply it by `100`, resulting in `1240` cents. - `currency` string, required — The payment currency.

Currently `EUR` is the only currency supported. - `token` string — The token required to charge the consumer wallet.
It can be an HOTP token.

Required with `HOTP_AUTH` flow only. - `consumer_uid` string — The unique id of the consumer required for payment acceptance.
To obtain the customer id, please use the [Get Consumer API](https://developers.satispay.com/reference/retrive-consumer).

Required with `MATCH_USER` flow only.

This parameter is deprecated; we suggest avoiding the `MATCH_USER` UX unless absolutely necessary. - `parent_payment_uid` string — The id of the payment that you want to refund.

Required with `REFUND` flow only. - `external_code` string — The external order id or payment identifier.

We highly recommend to use this field by populating it with your internal order id.
This string will be included in your reports for reconciliation and shown to the Satispay consumer in-app.

This field has a maximum length of 50 characters, including spaces. - `callback_url` string — The URL to be triggered via an HTTP GET request when there is a change in payment status.

When the given `callback_url` is invoked, a GET request for payment details can be made to retrieve the updated payment status.

Please note that `{uuid}` will be replaced with the generated payment id.
e.g. `https://example.com/satispay-callback?payment_id={uuid}`

You can read more [here](https://developers.satispay.com/reference/callback-s2s). - `redirect_url` string — This field specifies the URL where the user will be redirected after the payment flow from the Satispay app is completed.

For instance, you can set this URL to ensure users are redirected to that specific page upon successful payment completion.
e.g. `https://example.com/payment-redirect?order_id=your_order_id`

Please note that this field doesn't support any placeholder. - `metadata` object — The additional metadata for the payment.

This field supports up to 20 key-value pairs, with keys limited to 45 characters and values limited to 500 characters each. - `phone_number` string — This special metadata can be used to pre-fill the phone number field available if you're using a web-redirect flow.

The phone number must contain the prefix an shouldn't have any additional space.
e.g. `+393891122333` - `expiration_date` string — The UTC payment expiration datetime.

The format should be `ISO 8601` like this `yyyy-MM-dd'T'HH:mm:ss.SSSZ`.

By default `MATCH_CODE` and `MATCH_USER` payments are valid for 2 hours.

This parameter cannot be used with the `REFUND` flow. ## Response `200` OK - object - `id` string — The unique payment id.

This can be used for every eventual subsequent operations on the payment, including refunds. - `code_identifier` string — The Satispay code identifier.

This string can be encoded in a QR code that can be scanned by the user.
This property is only available in `MATCH_CODE` flow payments. - `type` string — The current payment type.

`TO_BUSINESS`
This type is used for payments from a consumer to a merchant.

`REFUND_TO_BUSINESS`
This type is used for payments from a merchant to a consumer (e.g. refunds). - `amount_unit` integer — The payment amount in cents.

For example, the amount `€12.40` is being represented as `1240` cents.
- `currency` 'EUR' — The payment currency. - `status` string — The current payment status.

`PENDING`
The payment is created and awaits user interaction, such as scanning the QR code.

- `expired` boolean — The current payment expiration status.

It becomes `true` once it reaches the `expiration_date` without being accepted or canceled. - `metadata` object — The additional metadata for the payment. - `sender` object — The sender payment actor. - `id` string — The unique sender id.

This will only be available once the payment will be matched with a consumer. - `type` string — The sender type.

`CONSUMER`
This sender type is used when the payment goes from a consumer to a merchant.

`SHOP`
This sender type is used when the payment goes from a merchant to a consumer (e.g. refunds payments). - `name` string — The sender name.

This will only be available once the payment will be matched with a consumer. - `receiver` object — The receiver payment actor. - `id` string — The unique receiver id. - `type` string — The receiver type.

`CONSUMER`
This receiver type is used when the payment goes from a merchant to a consumer.

`SHOP`
This receiver type is used when the payment goes from a consumer to a merchant (e.g. refunds payments). - `insert_date` string — The UTC payment creation datetime. - `expire_date` string — The UTC payment expiration datetime.

This property can be ignored when using `PRE_AUTHORIZED` or `HOTP_AUTH` flows. - `description` string — The external_code set during the payment creation request.

Please use the `external_code` field instead. - `flow` string - `external_code` string — The `external_code` set during the creation request. - `redirect_url` string — The URL where to redirect the user to begin the Satispay payment flow. ## Other responses - `400` — 400 Bad Request - `401` — 401 Unauthorized - `403` — 403 Forbidden or invalid authorization header --- [API](https://skmtc.net/satispay/apis/satispay-gbusiness-api.md) · [All operations](https://skmtc.net/satispay/apis/satispay-gbusiness-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/satispay/satispay-gbusiness-api/versions/f91f20a37e6f/schema)